home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 1998 November
/
Freeware November 1998.img
/
dist
/
fw_elisp-manual-19.idb
/
usr
/
freeware
/
info
/
elisp-24.z
/
elisp-24
(
.txt
)
Wrap
GNU Info File
|
1998-05-26
|
52KB
|
947 lines
This is Info file elisp, produced by Makeinfo-1.63 from the input file
elisp.texi.
This version is the edition 2.4.2 of the GNU Emacs Lisp Reference
Manual. It corresponds to Emacs Version 19.34.
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.
File: elisp, Node: Frame Parameters, Next: Frame Titles, Prev: Multiple Displays, Up: Frames
Frame Parameters
================
A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.
Frame parameters exist for the sake of window systems. A terminal
frame has a few parameters, mostly for compatibility's sake; only the
height, width and `buffer-predicate' parameters really do something.
* Menu:
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
* X Frame Parameters:: List of frame parameters.
* Size and Position:: Changing the size and position of a frame.
File: elisp, Node: Parameter Access, Next: Initial Parameters, Up: Frame Parameters
Access to Frame Parameters
--------------------------
These functions let you read and change the parameter values of a
frame.
- Function: frame-parameters FRAME
The function `frame-parameters' returns an alist listing all the
parameters of FRAME and their values.
- Function: modify-frame-parameters FRAME ALIST
This function alters the parameters of frame FRAME based on the
elements of ALIST. Each element of ALIST has the form `(PARM .
VALUE)', where PARM is a symbol naming a parameter. If you don't
mention a parameter in ALIST, its value doesn't change.
File: elisp, Node: Initial Parameters, Next: X Frame Parameters, Prev: Parameter Access, Up: Frame Parameters
Initial Frame Parameters
------------------------
You can specify the parameters for the initial startup frame by
setting `initial-frame-alist' in your `.emacs' file.
- Variable: initial-frame-alist
This variable's value is an alist of parameter values used when
creating the initial X window frame. You can set this variable to
specify the appearance of the initial frame without altering
subsequent frames. Each element has the form:
(PARAMETER . VALUE)
Emacs creates the initial frame before it reads your `~/.emacs'
file. After reading that file, Emacs checks `initial-frame-alist',
and applies the parameter settings in the altered value to the
already created initial frame.
If these settings affect the frame geometry and appearance, you'll
see the frame appear with the wrong ones and then change to the
specified ones. If that bothers you, you can specify the same
geometry and appearance with X resources; those do take affect
before the frame is created. *Note X Resources: (emacs)Resources
X.
X resource settings typically apply to all frames. If you want to
specify some X resources solely for the sake of the initial frame,
and you don't want them to apply to subsequent frames, here's how
to achieve this. Specify parameters in `default-frame-alist' to
override the X resources for subsequent frames; then, to prevent
these from affecting the initial frame, specify the same
parameters in `initial-frame-alist' with values that match the X
resources.
If these parameters specify a separate minibuffer-only frame with
`(minibuffer . nil)', and you have not created one, Emacs creates one
for you.
- Variable: minibuffer-frame-alist
This variable's value is an alist of parameter values used when
creating an initial minibuffer-only frame--if such a frame is
needed, according to the parameters for the main initial frame.
- Variable: default-frame-alist
This is an alist specifying default values of frame parameters for
all Emacs frames--the first frame, and subsequent frames. In many
cases, you can get the same results by means of X resources.
See also `special-display-frame-alist', in *Note Choosing Window::.
If you use options that specify window appearance when you invoke
Emacs, they take effect by adding elements to `default-frame-alist'.
One exception is `-geometry', which adds the specified position to
`initial-frame-alist' instead. *Note Command Arguments: (emacs)Command
Arguments.
File: elisp, Node: X Frame Parameters, Next: Size and Position, Prev: Initial Parameters, Up: Frame Parameters
X Window Frame Parameters
-------------------------
Just what parameters a frame has depends on what display mechanism it
uses. Here is a table of the parameters of an X window frame; of these,
`name', `height', `width', and `buffer-predicate' provide meaningful
information in non-X frames.
`name'
The name of the frame. Most window managers display the frame's
name in the frame's border, at the top of the frame. If you don't
specify a name, and you have more than one frame, Emacs sets the
frame name based on the buffer displayed in the frame's selected
window.
If you specify the frame name explicitly when you create the
frame, the name is also used (instead of the name of the Emacs
executable) when looking up X resources for the frame.
`display'
The display on which to open this frame. It should be a string of
the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
variable.
`left'
The screen position of the left edge, in pixels, with respect to
the left edge of the screen. The value may be a positive number
POS, or a list of the form `(+ POS)' which permits specifying a
negative POS value.
A negative number -POS, or a list of the form `(- POS)', actually
specifies the position of the right edge of the window with
respect to the right edge of the screen. A positive value of POS
counts toward the left. If the parameter is a negative integer
-POS then POS is positive!
Some window managers ignore program-specified positions. If you
want to be sure the position you specify is not ignored, specify a
non-`nil' value for the `user-position' parameter as well.
`top'
The screen position of the top edge, in pixels, with respect to the
top edge of the screen. The value may be a positive number POS,
or a list of the form `(+ POS)' which permits specifying a
negative POS value.
A negative number -POS, or a list of the form `(- POS)', actually
specifies the position of the bottom edge of the window with
respect to the bottom edge of the screen. A positive value of POS
counts toward the top. If the parameter is a negative integer
-POS then POS is positive!
Some window managers ignore program-specified positions. If you
want to be sure the position you specify is not ignored, specify a
non-`nil' value for the `user-position' parameter as well.
`icon-left'
The screen position of the left edge *of the frame's icon*, in
pixels, counting from the left edge of the screen. This takes
effect if and when the frame is iconified.
`icon-top'
The screen position of the top edge *of the frame's icon*, in
pixels, counting from the top edge of the screen. This takes
effect if and when the frame is iconified.
`user-position'
When you create a frame and specify its screen position with the
`left' and `top' parameters, use this parameter to say whether the
specified position was user-specified (explicitly requested in some
way by a human user) or merely program-specified (chosen by a
program). A non-`nil' value says the position was user-specified.
Window managers generally heed user-specified positions, and some
heed program-specified positions too. But many ignore
program-specified positions, placing the window in a default
fashion or letting the user place it with the mouse. Some window
managers, including `twm', let the user specify whether to obey
program-specified positions or ignore them.
When you call `make-frame', you should specify a non-`nil' value
for this parameter if the values of the `left' and `top'
parameters represent the user's stated preference; otherwise, use
`nil'.
`height'
The height of the frame contents, in characters. (To get the
height in pixels, call `frame-pixel-height'; see *Note Size and
Position::.)
`width'
The width of the frame contents, in characters. (To get the
height in pixels, call `frame-pixel-width'; see *Note Size and
Position::.)
`window-id'
The number of the X window for the frame.
`minibuffer'
Whether this frame has its own minibuffer. The value `t' means
yes, `nil' means no, `only' means this frame is just a minibuffer.
If the value is a minibuffer window (in some other frame), the
new frame uses that minibuffer.
`buffer-predicate'
The buffer-predicate function for this frame. The function
`other-buffer' uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
`nil'. It calls the predicate with one arg, a buffer, once for
each buffer; if the predicate returns a non-`nil' value, it
considers that buffer.
`font'
The name of the font for displaying text in the frame. This is a
string.
`auto-raise'
Whether selecting the frame raises it (non-`nil' means yes).
`auto-lower'
Whether deselecting the frame lowers it (non-`nil' means yes).
`vertical-scroll-bars'
Whether the frame has scroll bars for vertical scrolling
(non-`nil' means yes).
`horizontal-scroll-bars'
Whether the frame has scroll bars for horizontal scrolling
(non-`nil' means yes). (Horizontal scroll bars are not currently
implemented.)
`scroll-bar-width'
The width of the vertical scroll bar, in pixels.
`icon-type'
The type of icon to use for this frame when it is iconified. If
the value is a string, that specifies a file containing a bitmap
to use. Any other non-`nil' value specifies the default bitmap
icon (a picture of a gnu); `nil' specifies a text icon.
`icon-name'
The name to use in the icon for this frame, when and if the icon
appears. If this is `nil', the frame's title is used.
`foreground-color'
The color to use for the image of a character. This is a string;
the X server defines the meaningful color names.
`background-color'
The color to use for the background of characters.
`mouse-color'
The color for the mouse pointer.
`cursor-color'
The color for the cursor that shows point.
`border-color'
The color for the border of the frame.
`cursor-type'
The way to display the cursor. The legitimate values are `bar',
`box', and `(bar . WIDTH)'. The symbol `box' specifies an
ordinary black box overlaying the character after point; that is
the default. The symbol `bar' specifies a vertical bar between
characters as the cursor. `(bar . WIDTH)' specifies a bar WIDTH
pixels wide.
`border-width'
The width in pixels of the window border.
`internal-border-width'
The distance in pixels between text and border.
`unsplittable'
If non-`nil', this frame's window is never split automatically.
`visibility'
The state of visibility of the frame. There are three
possibilities: `nil' for invisible, `t' for visible, and `icon' for
iconified. *Note Visibility of Frames::.
`menu-bar-lines'
The number of lines to allocate at the top of the frame for a menu
bar. The default is 1. *Note Menu Bar::. (In Emacs versions
that use the X toolkit, there is only one menu bar line; all that
matters about the number you specify is whether it is greater than
zero.)
`parent-id'
The X window number of the window that should be the parent of
this one. Specifying this lets you create an Emacs window inside
some other application's window. (It is not certain this will be
implemented; try it and see if it works.)
File: elisp, Node: Size and Position, Prev: X Frame Parameters, Up: Frame Parameters
Frame Size And Position
-----------------------
You can read or change the size and position of a frame using the
frame parameters `left', `top', `height', and `width'. Whatever
geometry parameters you don't specify are chosen by the window manager
in its usual fashion.
Here are some special features for working with sizes and positions:
- Function: set-frame-position FRAME LEFT TOP
This function sets the position of the top left corner of FRAME to
LEFT and TOP. These arguments are measured in pixels, and count
from the top left corner of the screen. Negative parameter values
count up or rightward from the top left corner of the screen.
- Function: frame-height &optional FRAME
- Function: frame-width &optional FRAME
These functions return the height and width of FRAME, measured in
characters. If you don't supply FRAME, they use the selected
frame.
- Function: frame-pixel-height &optional FRAME
- Function: frame-pixel-width &optional FRAME
These functions return the height and width of FRAME, measured in
pixels. If you don't supply FRAME, they use the selected frame.
- Function: frame-char-height &optional FRAME
- Function: frame-char-width &optional FRAME
These functions return the height and width of a character in
FRAME, measured in pixels. The values depend on the choice of
font. If you don't supply FRAME, these functions use the selected
frame.
- Function: set-frame-size FRAME COLS ROWS
This function sets the size of FRAME, measured in characters; COLS
and ROWS specify the new width and height.
To set the size based on values measured in pixels, use
`frame-char-height' and `frame-char-width' to convert them to
units of characters.
The old-fashioned functions `set-screen-height' and
`set-screen-width', which were used to specify the height and width of
the screen in Emacs versions that did not support multiple frames, are
still usable. They apply to the selected frame. *Note Screen Size::.
- Function: x-parse-geometry GEOM
The function `x-parse-geometry' converts a standard X windows
geometry string to an alist that you can use as part of the
argument to `make-frame'.
The alist describes which parameters were specified in GEOM, and
gives the values specified for them. Each element looks like
`(PARAMETER . VALUE)'. The possible PARAMETER values are `left',
`top', `width', and `height'.
For the size parameters, the value must be an integer. The
position parameter names `left' and `top' are not totally accurate,
because some values indicate the position of the right or bottom
edges instead. These are the VALUE possibilities for the position
parameters:
an integer
A positive integer relates the left edge or top edge of the
window to the left or top edge of the screen. A negative
integer relates the right or bottom edge of the window to the
right or bottom edge of the screen.
`(+ POSITION)'
This specifies the position of the left or top edge of the
window relative to the left or top edge of the screen. The
integer POSITION may be positive or negative; a negative
value specifies a position outside the screen.
`(- POSITION)'
This specifies the position of the right or bottom edge of
the window relative to the right or bottom edge of the
screen. The integer POSITION may be positive or negative; a
negative value specifies a position outside the screen.
Here is an example:
(x-parse-geometry "35x70+0-0")
=> ((width . 35) (height . 70)
(left . 0) (top - 0))
File: elisp, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Parameters, Up: Frames
Frame Titles
============
Every frame has a title; most window managers display the frame
title at the top of the frame. You can specify an explicit title with
the `name' frame property. But normally you don't specify this
explicitly, and Emacs computes the title automatically.
Emacs computes the frame title based on a template stored in the
variable `frame-title-format'.
- Variable: frame-title-format
This variable specifies how to compute a title for a frame when
you have not explicitly specified one.
The variable's value is actually a mode line construct, just like
`mode-line-format'. *Note Mode Line Data::.
- Variable: icon-title-format
This variable specifies how to compute the title for an iconified
frame, when you have not explicitly specified the frame title.
This title appears in the icon itself.
- Variable: multiple-frames
This variable is set automatically by Emacs. Its value is `t' when
there are two or more frames (not counting minibuffer-only frames
or invisible frames). The default value of `frame-title-format'
uses `multiple-frames' so as to put the buffer name in the frame
title only when there is more than one frame.
File: elisp, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
Deleting Frames
===============
Frames remain potentially visible until you explicitly "delete"
them. A deleted frame cannot appear on the screen, but continues to
exist as a Lisp object until there are no references to it. There is no
way to cancel the deletion of a frame aside from restoring a saved frame
configuration (*note Frame Configurations::.); this is similar to the
way windows behave.
- Command: delete-frame &optional FRAME
This function deletes the frame FRAME. By default, FRAME is the
selected frame.
- Function: frame-live-p FRAME
The function `frame-live-p' returns non-`nil' if the frame FRAME
has not been deleted.
Some window managers provide a command to delete a window. These
work by sending a special message to the program that operates the
window. When Emacs gets one of these commands, it generates a
`delete-frame' event, whose normal definition is a command that calls
the function `delete-frame'. *Note Misc Events::.
File: elisp, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
Finding All Frames
==================
- Function: frame-list
The function `frame-list' returns a list of all the frames that
have not been deleted. It is analogous to `buffer-list' for
buffers. The list that you get is newly created, so modifying the
list doesn't have any effect on the internals of Emacs.
- Function: visible-frame-list
This function returns a list of just the currently visible frames.
*Note Visibility of Frames::. (Terminal frames always count as
"visible", even though only the selected one is actually
displayed.)
- Function: next-frame &optional FRAME MINIBUF
The function `next-frame' lets you cycle conveniently through all
the frames from an arbitrary starting point. It returns the "next"
frame after FRAME in the cycle. If FRAME is omitted or `nil', it
defaults to the selected frame.
The second argument, MINIBUF, says which frames to consider:
`nil'
Exclude minibuffer-only frames.
`visible'
Consider all visible frames.
0
Consider all visible or iconified frames.
a window
Consider only the frames using that particular window as their
minibuffer.
anything else
Consider all frames.
- Function: previous-frame &optional FRAME MINIBUF
Like `next-frame', but cycles through all frames in the opposite
direction.
See also `next-window' and `previous-window', in *Note Cyclic Window
Ordering::.
File: elisp, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
Frames and Windows
==================
Each window is part of one and only one frame; you can get the frame
with `window-frame'.
- Function: window-frame WINDOW
This function returns the frame that WINDOW is on.
All the non-minibuffer windows in a frame are arranged in a cyclic
order. The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.
- Function: frame-top-window FRAME
This returns the topmost, leftmost window of frame FRAME.
At any time, exactly one window on any frame is "selected within the
frame". The significance of this designation is that selecting the
frame also selects this window. You can get the frame's current
selected window with `frame-selected-window'.
- Function: frame-selected-window FRAME
This function returns the window on FRAME that is selected within
FRAME.
Conversely, selecting a window for Emacs with `select-window' also
makes that window selected within its frame. *Note Selecting Windows::.
Another function that (usually) returns one of the windows in a
frame is `minibuffer-window'. *Note Minibuffer Misc::.
File: elisp, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
Minibuffers and Frames
======================
Normally, each frame has its own minibuffer window at the bottom,
which is used whenever that frame is selected. If the frame has a
minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
Misc::.).
However, you can also create a frame with no minibuffer. Such a
frame must use the minibuffer window of some other frame. When you
create the frame, you can specify explicitly the minibuffer window to
use (in some other frame). If you don't, then the minibuffer is found
in the frame which is the value of the variable
`default-minibuffer-frame'. Its value should be a frame that does have
a minibuffer.
If you use a minibuffer-only frame, you might want that frame to
raise when you enter the minibuffer. If so, set the variable
`minibuffer-auto-raise' to `t'. *Note Raising and Lowering::.
- Variable: default-minibuffer-frame
This variable specifies the frame to use for the minibuffer
window, by default. It is always local to the current terminal
and cannot be buffer-local. *Note Multiple Displays::.
File: elisp, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
Input Focus
===========
At any time, one frame in Emacs is the "selected frame". The
selected window always resides on the selected frame.
- Function: selected-frame
This function returns the selected frame.
The X server normally directs keyboard input to the X window that the
mouse is in. Some window managers use mouse clicks or keyboard events
to "shift the focus" to various X windows, overriding the normal
behavior of the server.
Lisp programs can switch frames "temporarily" by calling the
function `select-frame'. This does not override the window manager;
rather, it escapes from the window manager's control until that control
is somehow reasserted.
When using a text-only terminal, there is no window manager;
therefore, `switch-frame' is the only way to switch frames, and the
effect lasts until overridden by a subsequent call to `switch-frame'.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
`Emacs' (*note Mode Line Variables::.).
- Function: select-frame FRAME
This function selects frame FRAME, temporarily disregarding the
focus of the X server if any. The selection of FRAME lasts until
the next time the user does something to select a different frame,
or until the next time this function is called.
Emacs cooperates with the X server and the window managers by
arranging to select frames according to what the server and window
manager ask for. It does so by generating a special kind of input
event, called a "focus" event. The command loop handles a focus event
by calling `handle-switch-frame'. *Note Focus Events::.
- Command: handle-switch-frame FRAME
This function handles a focus event by selecting frame FRAME.
Focus events normally do their job by invoking this command.
Don't call it for any other reason.
- Function: redirect-frame-focus FRAME FOCUS-FRAME
This function redirects focus from FRAME to FOCUS-FRAME. This
means that FOCUS-FRAME will receive subsequent keystrokes intended
for FRAME. After such an event, the value of `last-event-frame'
will be FOCUS-FRAME. Also, switch-frame events specifying FRAME
will instead select FOCUS-FRAME.
If FOCUS-FRAME is `nil', that cancels any existing redirection for
FRAME, which therefore once again receives its own events.
One use of focus redirection is for frames that don't have
minibuffers. These frames use minibuffers on other frames.
Activating a minibuffer on another frame redirects focus to that
frame. This puts the focus on the minibuffer's frame, where it
belongs, even though the mouse remains in the frame that activated
the minibuffer.
Selecting a frame can also change focus redirections. Selecting
frame `bar', when `foo' had been selected, changes any redirections
pointing to `foo' so that they point to `bar' instead. This
allows focus redirection to work properly when the user switches
from one frame to another using `select-window'.
This means that a frame whose focus is redirected to itself is
treated differently from a frame whose focus is not redirected.
`select-frame' affects the former but not the latter.
The redirection lasts until `redirect-frame-focus' is called to
change it.
File: elisp, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
Visibility of Frames
====================
An X window frame may be "visible", "invisible", or "iconified". If
it is visible, you can see its contents. If it is iconified, the
frame's contents do not appear on the screen, but an icon does. If the
frame is invisible, it doesn't show on the screen, not even as an icon.
Visibility is meaningless for terminal frames, since only the
selected one is actually displayed in any case.
- Command: make-frame-visible &optional FRAME
This function makes frame FRAME visible. If you omit FRAME, it
makes the selected frame visible.
- Command: make-frame-invisible &optional FRAME
This function makes frame FRAME invisible. If you omit FRAME, it
makes the selected frame invisible.
- Command: iconify-frame &optional FRAME
This function iconifies frame FRAME. If you omit FRAME, it
iconifies the selected frame.
- Function: frame-visible-p FRAME
This returns the visibility status of frame FRAME. The value is
`t' if FRAME is visible, `nil' if it is invisible, and `icon' if
it is iconified.
The visibility status of a frame is also available as a frame
parameter. You can read or change it as such. *Note X Frame
Parameters::.
The user can iconify and deiconify frames with the window manager.
This happens below the level at which Emacs can exert any control, but
Emacs does provide events that you can use to keep track of such
changes. *Note Misc Events::.
File: elisp, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
Raising and Lowering Frames
===========================
The X Window System uses a desktop metaphor. Part of this metaphor
is the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from "highest" to
"lowest". Where two windows overlap, the one higher up covers the one
underneath. Even a window at the bottom of the stack can be seen if no
other window overlaps it.
A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. "Raising" a window means moving it
"up", to the top of the stack. "Lowering" a window means moving it to
the bottom of the stack. This motion is in the notional third
dimension only, and does not change the position of the window on the
screen.
You can raise and lower Emacs's X windows with these functions:
- Command: raise-frame FRAME
This function raises frame FRAME.
- Command: lower-frame FRAME
This function lowers frame FRAME.
- User Option: minibuffer-auto-raise
If this is non-`nil', activation of the minibuffer raises the frame
that the minibuffer window is in.
You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
for any frame using frame parameters. *Note X Frame Parameters::.
File: elisp, Node: Frame Configurations, Next: Mouse Tracking, Prev: Raising and Lowering, Up: Frames
Frame Configurations
====================
A "frame configuration" records the current arrangement of frames,
all their properties, and the window configuration of each one.
- Function: current-frame-configuration
This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
- Function: set-frame-configuration CONFIGURATION
This function restores the state of frames described in
CONFIGURATION.
File: elisp, Node: Mouse Tracking, Next: Mouse Position, Prev: Frame Configurations, Up: Frames
Mouse Tracking
==============
Sometimes it is useful to "track" the mouse, which means to display
something to indicate where the mouse is and move the indicator as the
mouse moves. For efficient mouse tracking, you need a way to wait until
the mouse actually moves.
The convenient way to track the mouse is to ask for events to
represent mouse motion. Then you can wait for motion by waiting for an
event. In addition, you can easily handle any other sorts of events
that may occur. That is useful, because normally you don't want to
track the mouse forever--only until some other event, such as the
release of a button.
- Special Form: track-mouse BODY...
Execute BODY, meanwhile generating input events for mouse motion.
The code in BODY can read these events with `read-event' or
`read-key-sequence'. *Note Motion Events::, for the format of
mouse motion events.
The value of `track-mouse' is that of the last form in BODY.
The usual purpose of tracking mouse motion is to indicate on the
screen the consequences of pushing or releasing a button at the current
position.
In many cases, you can avoid the need to track the mouse by using
the `mouse-face' text property (*note Special Properties::.). That
works at a much lower level and runs more smoothly than Lisp-level
mouse tracking.
File: elisp, Node: Mouse Position, Next: Pop-Up Menus, Prev: Mouse Tracking, Up: Frames
Mouse Position
==============
The functions `mouse-position' and `set-mouse-position' give access
to the current position of the mouse.
- Function: mouse-position
This function returns a description of the position of the mouse.
The value looks like `(FRAME X . Y)', where X and Y are integers
giving the position in characters relative to the top left corner
of the inside of FRAME.
- Function: set-mouse-position FRAME X Y
This function "warps the mouse" to position X, Y in frame FRAME.
The arguments X and Y are integers, giving the position in
characters relative to the top left corner of the inside of FRAME.
- Function: mouse-pixel-position
This function is like `mouse-position' except that it returns
coordinates in units of pixels rather than units of characters.
- Function: set-mouse-pixel-position FRAME X Y
This function warps the mouse like `set-mouse-position' except that
X and Y are in units of pixels rather than units of characters.
These coordinates are not required to be within the frame.
File: elisp, Node: Pop-Up Menus, Next: Dialog Boxes, Prev: Mouse Position, Up: Frames
Pop-Up Menus
============
When using X windows, a Lisp program can pop up a menu which the
user can choose from with the mouse.
- Function: x-popup-menu POSITION MENU
This function displays a pop-up menu and returns an indication of
what selection the user makes.
The argument POSITION specifies where on the screen to put the
menu. It can be either a mouse button event (which says to put
the menu where the user actuated the button) or a list of this
form:
((XOFFSET YOFFSET) WINDOW)
where XOFFSET and YOFFSET are coordinates, measured in pixels,
counting from the top left corner of WINDOW's frame.
If POSITION is `t', it means to use the current mouse position.
If POSITION is `nil', it means to precompute the key binding
equivalents for the keymaps specified in MENU, without actually
displaying or popping up the menu.
The argument MENU says what to display in the menu. It can be a
keymap or a list of keymaps (*note Menu Keymaps::.).
Alternatively, it can have the following form:
(TITLE PANE1 PANE2...)
where each pane is a list of form
(TITLE (LINE . ITEM)...)
Each LINE should be a string, and each ITEM should be the value to
return if that LINE is chosen.
*Usage note:* Don't use `x-popup-menu' to display a menu if a prefix
key with a menu keymap would do the job. If you use a menu keymap to
implement a menu, `C-h c' and `C-h a' can see the individual items in
that menu and provide help for them. If instead you implement the menu
by defining a command that calls `x-popup-menu', the help facilities
cannot know what happens inside that command, so they cannot give any
help for the menu's items.
The menu bar mechanism, which lets you switch between submenus by
moving the mouse, cannot look within the definition of a command to see
that it calls `x-popup-menu'. Therefore, if you try to implement a
submenu using `x-popup-menu', it cannot work with the menu bar in an
integrated fashion. This is why all menu bar submenus are implemented
with menu keymaps within the parent menu, and never with
`x-popup-menu'. *Note Menu Bar::,
If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it. To make the contents vary, add
a hook function to `menu-bar-update-hook' to update the contents of the
menu keymap as necessary.
File: elisp, Node: Dialog Boxes, Next: Pointer Shapes, Prev: Pop-Up Menus, Up: Frames
Dialog Boxes
============
A dialog box is a variant of a pop-up menu. It looks a little
different (if Emacs uses an X toolkit), it always appears in the center
of a frame, and it has just one level and one pane. The main use of
dialog boxes is for asking questions that the user can answer with
"yes", "no", and a few other alternatives. The functions `y-or-n-p'
and `yes-or-no-p' use dialog boxes instead of the keyboard, when called
from commands invoked by mouse clicks.
- Function: x-popup-dialog POSITION CONTENTS
This function displays a pop-up dialog box and returns an
indication of what selection the user makes. The argument
CONTENTS specifies the alternatives to offer; it has this format:
(TITLE (STRING . VALUE)...)
which looks like the list that specifies a single pane for
`x-popup-menu'.
The return value is VALUE from the chosen alternative.
An element of the list may be just a string instead of a cons cell
`(STRING . VALUE)'. That makes a box that cannot be selected.
If `nil' appears in the list, it separates the left-hand items from
the right-hand items; items that precede the `nil' appear on the
left, and items that follow the `nil' appear on the right. If you
don't include a `nil' in the list, then approximately half the
items appear on each side.
Dialog boxes always appear in the center of a frame; the argument
POSITION specifies which frame. The possible values are as in
`x-popup-menu', but the precise coordinates don't matter; only the
frame matters.
If your Emacs executable does not use an X toolkit, then it cannot
display a real dialog box; so instead it displays the same items
in a pop-up menu in the center of the frame.
File: elisp, Node: Pointer Shapes, Next: X Selections, Prev: Dialog Boxes, Up: Frames
Pointer Shapes
==============
These variables specify which shape to use for the mouse pointer in
various situations:
`x-pointer-shape'
This variable specifies the pointer shape to use ordinarily in the
Emacs frame.
`x-sensitive-text-pointer-shape'
This variable specifies the pointer shape to use when the mouse is
over mouse-sensitive text.
These variables affect newly created frames. They do not normally
affect existing frames; however, if you set the mouse color of a frame,
that also updates its pointer shapes based on the current values of
these variables. *Note X Frame Parameters::.
The values you can use, to specify either of these pointer shapes,
are defined in the file `lisp/term/x-win.el'. Use `M-x apropos RET
x-pointer RET' to see a list of them.
File: elisp, Node: X Selections, Next: Color Names, Prev: Pointer Shapes, Up: Frames
X Selections
============
The X server records a set of "selections" which permit transfer of
data between application programs. The various selections are
distinguished by "selection types", represented in Emacs by symbols. X
clients including Emacs can read or set the selection for any given
type.
- Function: x-set-selection TYPE DATA
This function sets a "selection" in the X server. It takes two
arguments: a selection type TYPE, and the value to assign to it,
DATA. If DATA is `nil', it means to clear out the selection.
Otherwise, DATA may be a string, a symbol, an integer (or a cons
of two integers or list of two integers), an overlay, or a cons of
two markers pointing to the same buffer. An overlay or a pair of
markers stands for text in the overlay or between the markers.
The data may also be a vector of valid non-vector selection values.
Each possible TYPE has its own selection value, which changes
independently. The usual values of TYPE are `PRIMARY' and
`SECONDARY'; these are symbols with upper-case names, in accord
with X Window System conventions. The default is `PRIMARY'.
- Function: x-get-selection &optional TYPE DATA-TYPE
This function accesses selections set up by Emacs or by other X
clients. It takes two optional arguments, TYPE and DATA-TYPE.
The default for TYPE, the selection type, is `PRIMARY'.
The DATA-TYPE argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into
Lisp data. Meaningful values include `TEXT', `STRING', `TARGETS',
`LENGTH', `DELETE', `FILE_NAME', `CHARACTER_POSITION',
`LINE_NUMBER', `COLUMN_NUMBER', `OWNER_OS', `HOST_NAME', `USER',
`CLASS', `NAME', `ATOM', and `INTEGER'. (These are symbols with
upper-case names in accord with X conventions.) The default for
DATA-TYPE is `STRING'.
The X server also has a set of numbered "cut buffers" which can
store text or other data being moved between applications. Cut buffers
are considered obsolete, but Emacs supports them for the sake of X
clients that still use them.
- Function: x-get-cut-buffer N
This function returns the contents of cut buffer number N.
- Function: x-set-cut-buffer STRING
This function stores STRING into the first cut buffer (cut buffer
0), moving the other values down through the series of cut
buffers, much like the way successive kills in Emacs move down the
kill ring.
File: elisp, Node: Color Names, Next: Resources, Prev: X Selections, Up: Frames
Color Names
===========
- Function: x-color-defined-p COLOR &optional FRAME
This function reports whether a color name is meaningful. It
returns `t' if so; otherwise, `nil'. The argument FRAME says
which frame's display to ask about; if FRAME is omitted or `nil',
the selected frame is used.
Note that this does not tell you whether the display you are using
really supports that color. You can ask for any defined color on
any kind of display, and you will get some result--that is how the
X server works. Here's an approximate way to test whether your
display supports the color COLOR:
(defun x-color-supported-p (color &optional frame)
(and (x-color-defined-p color frame)
(or (x-display-color-p frame)
(member color '("black" "white"))
(and (> (x-display-planes frame) 1)
(equal color "gray")))))
- Function: x-color-values COLOR &optional FRAME
This function returns a value that describes what COLOR should
ideally look like. If COLOR is defined, the value is a list of
three integers, which give the amount of red, the amount of green,
and the amount of blue. Each integer ranges in principle from 0
to 65535, but in practice no value seems to be above 65280. If
COLOR is not defined, the value is `nil'.
(x-color-values "black")
=> (0 0 0)
(x-color-values "white")
=> (65280 65280 65280)
(x-color-values "red")
=> (65280 0 0)
(x-color-values "pink")
=> (65280 49152 51968)
(x-color-values "hungry")
=> nil
The color values are returned for FRAME's display. If FRAME is
omitted or `nil', the information is return for the selected
frame's display.
File: elisp, Node: Resources, Next: Server Data, Prev: Color Names, Up: Frames
X Resources
===========
- Function: x-get-resource ATTRIBUTE CLASS &optional COMPONENT SUBCLASS
The function `x-get-resource' retrieves a resource value from the X
Windows defaults database.
Resources are indexed by a combination of a "key" and a "class".
This function searches using a key of the form
`INSTANCE.ATTRIBUTE' (where INSTANCE is the name under which Emacs
was invoked), and using `Emacs.CLASS' as the class.
The optional arguments COMPONENT and SUBCLASS add to the key and
the class, respectively. You must specify both of them or neither.
If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE',
and the class is `Emacs.CLASS.SUBCLASS'.
*Note X Resources: (emacs)Resources X.
File: elisp, Node: Server Data, Prev: Resources, Up: Frames
Data about the X Server
=======================
This section describes functions you can use to get information about
the capabilities and origin of an X display that Emacs is using. Each
of these functions lets you specify the display you are interested in:
the DISPLAY argument can be either a display name, or a frame (meaning
use the display that frame is on). If you omit the DISPLAY argument,
or specify `nil', that means to use the selected frame's display.
- Function: x-display-screens &optional DISPLAY
This function returns the number of screens associated with the
display.
- Function: x-server-version &optional DISPLAY
This function returns the list of version numbers of the X server
running the display.
- Function: x-server-vendor &optional DISPLAY
This function returns the vendor that provided the X server
software.
- Function: x-display-pixel-height &optional DISPLAY
This function returns the height of the screen in pixels.
- Function: x-display-mm-height &optional DISPLAY
This function returns the height of the screen in millimeters.
- Function: x-display-pixel-width &optional DISPLAY
This function returns the width of the screen in pixels.
- Function: x-display-mm-width &optional DISPLAY
This function returns the width of the screen in millimeters.
- Function: x-display-backing-store &optional DISPLAY
This function returns the backing store capability of the screen.
Values can be the symbols `always', `when-mapped', or `not-useful'.
- Function: x-display-save-under &optional DISPLAY
This function returns non-`nil' if the display supports the
SaveUnder feature.
- Function: x-display-planes &optional DISPLAY
This function returns the number of planes the display supports.
- Function: x-display-visual-class &optional DISPLAY
This function returns the visual class for the screen. The value
is one of the symbols `static-gray', `gray-scale', `static-color',
`pseudo-color', `true-color', and `direct-color'.
- Function: x-display-grayscale-p &optional DISPLAY
This function returns `t' if the screen can display shades of gray.
- Function: x-display-color-p &optional DISPLAY
This function returns `t' if the screen is a color screen.
- Function: x-display-color-cells &optional DISPLAY
This function returns the number of color cells the screen
supports.
File: elisp, Node: Positions, Next: Markers, Prev: Frames, Up: Top
Positions
*********
A "position" is the index of a character in the text of a buffer.
More precisely, a position identifies the place between two characters
(or before the first character, or after the last character), so we can
speak of the character before or after a given position. However, we
often speak of the character "at" a position, meaning the character
after that position.
Positions are usually represented as integers starting from 1, but
can also be represented as "markers"--special objects that relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters. *Note Markers::.
* Menu:
* Point:: The special position where editing takes place.
* Motion:: Changing point.
* Excursions:: Temporary motion and buffer changes.
* Narrowing:: Restricting editing to a portion of the buffer.
File: elisp, Node: Point, Next: Motion, Up: Positions
Point
=====
"Point" is a special buffer position used by many editing commands,
including the self-inserting typed characters and text insertion
functions. Other commands move point through the text to allow editing
and insertion at different places.
Like other positions, point designates a place between two characters
(or before the first character, or after the last character), rather
than a particular character. Usually terminals display the cursor over
the character that immediately follows point; point is actually before
the character on which the cursor sits.
The value of point is a number between 1 and the buffer size plus 1.
If narrowing is in effect (*note Narrowing::.), then point is
constrained to fall within the accessible portion of the buffer
(possibly at one end of it).
Each buffer has its own value of point, which is independent of the
value of point in other buffers. Each window also has a value of point,
which is independent of the value of point in other windows on the same
buffer. This is why point can have different values in various windows
that display the same buffer. When a buffer appears in only one window,
the buffer's point and the window's point normally have the same value,
so the distinction is rarely important. *Note Window Point::, for more
details.
- Function: point
This function returns the value of point in the current buffer, as
an integer.
(point)
=> 175
- Function: point-min
This function returns the minimum accessible value of point in the
current buffer. This is normally 1, but if narrowing is in
effect, it is the position of the start of the region that you
narrowed to. (*Note Narrowing::.)
- Function: point-max
This function returns the maximum accessible value of point in the
current buffer. This is `(1+ (buffer-size))', unless narrowing is
in effect, in which case it is the position of the end of the
region that you narrowed to. (*Note Narrowing::).
- Function: buffer-end FLAG
This function returns `(point-min)' if FLAG is less than 1,
`(point-max)' otherwise. The argument FLAG must be a number.
- Function: buffer-size
This function returns the total number of characters in the current
buffer. In the absence of any narrowing (*note Narrowing::.),
`point-max' returns a value one larger than this.
(buffer-size)
=> 35
(point-max)
=> 36
File: elisp, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
Motion
======
Motion functions change the value of point, either relative to the
current value of point, relative to the beginning or end of the buffer,
or relative to the edges of the selected window. *Note Point::.
* Menu:
* Character Motion:: Moving in terms of characters.
* Word Motion:: Moving in terms of words.
* Buffer End Motion:: Moving to the beginning or end of the buffer.
* Text Lines:: Moving in terms of lines of text.
* Screen Lines:: Moving in terms of lines as displayed.
* List Motion:: Moving by parsing lists and sexps.
* Skipping Characters:: Skipping characters belonging to a certain set.